Chapitre 15 [dev] Développer un package documenté et testé avec la méthode ‘Rmd first’

Si vous travaillez sur Windows, vous aurez peut-être besoin d’installer les dépendances systèmes de Rtools pour les développeurs : https://cran.r-project.org/bin/windows/Rtools/

15.1 Développer

Tout développement avec R se déroule dans un package documenté, versionné, testé.

  • Créer et travailler dans une “branche-issue”
    • Vous pouvez créer une branche à partir de l’issue directement sur GitLab
  • Dans le “Board” GitLab, déplacer les issues en cours de traitement sous le label “En cours”
  • Créer les vignettes en fonction des parties majeures du développement
    • On développe toujours en “Rmd first” pour la reproductibilité du code : https://rtask.thinkr.fr/fr/quand-le-developpement-commence-par-la-documentation/
    • Utiliser usethis::use_vignette("aa-partie-exploration-des-donnees") (noté dans le fichier "dev_history.R")
    • Utiliser “aa”, “ab”, “bb”, … dans le %\VignetteIndexEntry{aa-partie-exploration-des-donnees} pour s’assurer de l’ordre d’apparition des vignettes dans le menu du Site {pkgdown}
    • Développer le code dans la vignette adéquate
    • Plusieurs fonctions du même groupe seront regroupées dans une même vignette
      • Exemple: une page de l’app Shiny / un chapitre = une vignette
      • Attention à la résolution des issues d’un même groupe qui peuvent engendrer des conflits de fichier dans les vignettes
    • Créer des nouvelles sous-vignettes au cours du développement en fonction du besoin quitte à les regrouper à la fin du développement pour plus de clarté dans le site {pkgdown}.
    • Créer les exemples reproductibles qui serviront à la documentation de chaque fonction
    • Utiliser la vignette pour les démos et propositions aux éditos et utilisateurs
  • Documenter les fonctions
    • Créer le squelette {roxygen2}
      • Commencer les descriptifs par une majuscule et finir par un point.
    • Importer les fonctions avec pkg::fun ou @importFrom
    • Mettre un exemple d’utilisation de la fonction

Exemple d’une vignette comprenant la fonction donne_l_heure() dans le package chatime:

  • Quand la fonction est prête, la mettre dans un fichier à part dans le dossier “R/”. Utiliser usethis::use_r("nom_de_la_fonction") (noté dans le fichier "dev_history.R")
  • Pensez à attachment::att_amend_desc()
  • Écrire les tests unitaires dans le dossier “tests/testthat/”
  • Utiliser l’addin Styler sur les fichiers du projets: styler::style_pkg()
    • Notez que vous pouvez sélectionner un morceau de code et faire “Ctrl + Shift + A” en cours d’écriture pour utiliser le reformattage natif de Rstudio
  • Faire les devtools::check() et viser “0 notes, 0 warning, 0 errors”
  • Remplir le “NEWS.md” avec les nouvelles fonctionnalités
  • Créer un commit avec les informations nécessaires (“Rédiger un message de commit informatif”)
    • Titre direct et explicite
    • Pourquoi
    • Quoi
    • Tickets / Issues en lien
  • Tester la bonne construction du site {pkgdown} en local
    • Tester l’intégration de la “covrpage”: covrpage::covrpage(vignette = TRUE)
  • Après envoi sur le serveur et fusion dans la branche de dev, vérifier que la documentation passe correctement sur les pages du site {pkgdown} du projet

Le package {fusen} permet de créer un package à partir d’un ou plusieurs RMarkdown. Les développeurs débutants, mais aussi les aguerris peuvent avoir envie de se focaliser sur le contenu de la future publication, plutôt que sur la façon de ranger les différents fichiers dans un package R. Plus d’informations dans l’article : “{fusen}: Créer un package à partir d’un simple fichier RMarkdown”

15.2 Utilisation de {renv} pour les versions de packages R

Votre projet est probablement configuré avec {renv}. Si c’est le cas, vous l’aurez remarqué depuis le premier jour grâce aux petits messages qu’il met dans votre console. {renv} permet de figer les versions de packages R utilisées pour le développement de ce projet en particulier. Après l’initialisation du projet avec {renv}, vous avez deux commandes principales à retenir :

  • renv::restore() à effectuer à chaque fois que vous intégrez les modifications des autres depuis le serveur pour se mettre dans les dernières conditions de travail
  • renv::snapshot() à effectuer juste avant d’envoyer vos modifications sur le serveur pour demander une fusion vers la branche de développement dev. Cette commande permet de renvoyer l’information des packages que vous êtes en train d’utiliser pour vos développement

{renv} explore la totalité de votre projet à la recherche des packages nécessaires à son bon fonctionnement. Cependant, il liste la totalité des packages que vous avez installés au cours de votre session, y compris ceux que vous avez décidé de ne pas utiliser finalement. Il est donc conseillé de choisir les packages à intégrer au fichier "renv.lock", pour éviter à chacun d’avoir à installer des packages inutiles. Ceci peut aussi réduire le temps d’installation des packages dans l’intégration continue. Pour cela, utilisez {attachment} pour vous aider :

# _renv
custom_packages <- c(
    # Les packages de votre projet
    attachment::att_from_description(),
    # Les packages nécessaires au développement
    "renv",
    "devtools", "roxygen2", "usethis",
    "testthat", "covr", "attachment",
    "pkgdown", "styler", "checkhelper")
# Store list of packages
renv::snapshot(packages = custom_packages)

La version complète des instructions à réaliser devrait se trouver dans votre fichier de développement "dev_history.R"

15.3 Documenter et tester pour les développeurs

Pensez au futur. Le futur, c’est le développement du contenu du chapitre 2. C’est aussi l’ajout de nouvelles fonctionnalités qui se feront dans 6 mois ou plus par vous ou vos futurs collaborateurs qui n’ont peut-être pas participé à la première phase du projet.

Votre principal collaborateur est vous-même dans 6 mois, et votre ancien moi ne répond pas aux e-mails Meghan Duffy : “The biggest benefit of my switch to R? Reproducibility”

Les vignettes montrent comment les fonctions sont utilisées. Les exemples reproductibles des différentes fonctions complètent la documentation du package. Les tests unitaires permettent de s’assurer que l’ajout de nouvelles fonctionnalités ne remet pas en question les fonctionnalités déjà implémentées.

15.4 Documenter pour les utilisateurs

Les personnes qui vont utiliser votre package ont besoin de savoir comment il fonctionne. Pour un package R classique, vos vignettes et la documentation des fonctions sont suffisants. Dans le cadre de la création d’une publication PROPRE, votre package permet de créer une livre numérique pré-rempli que les utilisateurs doivent apprendre à manipuler.

Il faudra :

  • Définir le contexte préalable d’utilisation (versions de R, des dépendances, encodage, accès aux données, …)
  • Expliquer comment installer le package R et ses dépendances
  • Expliquer comment utiliser/effectuer la création du squelette de base, et, si vous avez créé une interface graphique, comment l’utiliser
  • Expliquer comment-où-dans quelles conditions remplir le contenu, pour que le document final de chaque partenaire soit conforme aux besoins initiaux d’homogénéité des publications